[% setvar title Thread Programming Model %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Thread Programming Model</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Steven McDougall &lt;<a href='mailto:swmcd@world.std.com'>swmcd@world.std.com</a>&gt;
  Date: 31 Aug 2000
  Last Modified: 28 Sep 2000
  Version: 4
  Mailing List: <a href='mailto:perl6-language-flow@perl.org'>perl6-language-flow@perl.org</a>
  Number: 185
  Status: Developing
  Frozen since: v3
  Unfrozen since: v4</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>This RFC describes the programming interface to Perl6 threads.
It documents the function calls, operators, classes, methods, or
whatever else the language provides for programming with threads.</p>
<a name='CHANGES'></a><h1>CHANGES</h1>
<a name='v4'></a><h2>v4</h2>
<ul>
<li><a name='Unfrozen'></a>Unfrozen</li>
<li><a name='Traded in try for lock in boolean context'></a>Traded in <code>try</code> for <code>lock</code> in boolean context</li>
<li><a name='Traded in Event for condition variables'></a>Traded in <code>Event</code> for condition variables</li>
<li><a name='Reworked the timer functions'></a>Reworked the timer functions</li>
<li><a name='Dropped the I/O section'></a>Dropped the I/O section</li>
<li><a name='Dropped wait_any and wait_all'></a>Dropped <code>wait_any</code> and <code>wait_all</code></li>
<li><a name='Dropped Semaphore and Queue'></a>Dropped <code>Semaphore</code> and <code>Queue</code></li>
</ul>
<a name='v3'></a><h2>v3</h2>
<p>Frozen</p>
<a name='v2'></a><h2>v2</h2>
<ul>
<li><a name='Added SYNOPSIS, and wrote a proper ABSTRACT'></a>Added SYNOPSIS, and wrote a proper ABSTRACT</li>
<li><a name='Detailed async'></a>Detailed <code>async</code></li>
<li><a name='Detailed sharing of lexicals between threads'></a>Detailed sharing of lexicals between threads</li>
<li><a name='Traded Mutexes back for lock, try, and unlock'></a>Traded Mutexes back for <code>lock</code>, <code>try</code>, and <code>unlock</code></li>
<li><a name='Pushed Semaphore, Event, and Timer down into Thread::'></a>Pushed <code>Semaphore</code>, <code>Event</code>, and <code>Timer</code> down into <code>Thread::</code></li>
<li><a name='Specified readable, writable and failure to return Events'></a>Specified readable, writable and failure to return Events</li>
<li><a name='Reworked the wait functions'></a>Reworked the wait functions</li>
<li><a name='Added Queue'></a>Added <code>Queue</code></li>
</ul>
<a name='SYNOPSIS'></a><h1>SYNOPSIS</h1>
<pre>  use Thread;
  
  $sub = sub { ... };  
  
  $thread  = new Thread \&amp;func       , @args;
  $thread  = new Thread  $sub        , @args;
  $thread  = new Thread   sub { ... }, @args;
  	                async { ... };
  $result  = join $thread;
       
  $thread  = this Thread;
  @threads = all  Thread;
  
  $thread1 == $thread2 and ...
  Thread::yield();
    
  critical { ... };   # one thread at a time in this block

  # blocking  
  lock $scalar;
  lock @array
  lock %hash;
  lock &amp;sub;

  # non-blocking
  $ok = lock $scalar;
  $ok = lock @array
  $ok = lock %hash;
  $ok = lock &amp;sub;
  
  unlock $scalar;
  unlock @array
  unlock %hash;
  unlock &amp;sub;

  cond_wait      $mutex;
  cond_signal    $mutex;
  cond_broadcast $mutex;
  
  Thread::delay($seconds);
  Thread::alarm($time);
  </pre>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<a name='Thread'></a><h2>Thread</h2>
<ul>
<li><a name='$thread = new Thread \&amp;func, @args'></a><i>$thread</i> = <code>new</code> <code>Thread</code> \&amp;<i>func</i>, <i>@args</i></li>
<p>Executes <i>func</i>(<i>@args</i>) in a separate thread. The return value is
a reference to the <code>Thread</code> object that manages the thread.</p>
<p>The subroutine executes in its enclosing lexical context. This means
that lexical variables declared in that context may be shared between
threads. See RFC 178 for examples.</p>
<li><a name='$thread = new Thread $sub, @args'></a><i>$thread</i> = <code>new</code> <code>Thread</code> <i>$sub</i>, <i>@args</i></li>
<li><a name='$thread = new Thread sub { ... }, @args'></a><i>$thread</i> = <code>new</code> <code>Thread</code> <code>sub</code> { ... }, <i>@args</i></li>
<p>Executes an anonymous subroutine in a separate thread, passing it
<i>@args</i>. The return value is a reference to the <code>Thread</code> object that
manages the thread.</p>
<p>The subroutine is a closure. References to variables in its lexical
context are bound when the <code>sub</code> operator executes. See RFC 178 for
examples.</p>
<li><a name='async BLOCK'></a><code>async</code> BLOCK</li>
<p>Executes BLOCK in a separate thread. Syntactically, <code>async</code> BLOCK
works like <code>do</code> BLOCK. <code>async</code> creates a <code>Thread</code> object to manage
the thread, but it does not return a reference to it. If you want the
<code>Thread</code> object, use one of the <code>new</code> <code>Thread</code> forms shown above.</p>
<p>The BLOCK executes in its enclosing lexical context. This means that
lexical variables declared in that context may be shared between
threads.</p>
<li><a name='$thread = this Thread'></a><i>$thread</i> = <code>this</code> <code>Thread</code></li>
<p>Returns a reference to the <code>Thread</code> object that manages the current
thread.</p>
<li><a name='@threads = all Thread'></a><i>@threads</i> = <code>all</code> <code>Thread</code></li>
<p>Returns a list of references to all existing <code>Thread</code> objects in the
program. This includes <code>Thread</code> objects created for <code>async</code> blocks.</p>
<li><a name='$result = join $thread'></a><i>$result</i> = <code>join</code> <i>$thread</i></li>
<li><a name='@result = join $thread'></a><i>@result</i> = <code>join</code> <i>$thread</i></li>
<p>Blocks until <i>$thread</i> terminates. May be called repeatedly,
by any number of threads.</p>
<p>Returns the last expression evaluated in <i>$thread</i>. This expression
is evaluated in list context inside the thread.</p>
<p>If <code>join</code> is called in list context, it returns the entire list; if
<code>join</code> is called in scalar context, it returns the first element of
the list.</p>
<li><a name='$thread1 == $thread2'></a><i>$thread1</i> == <i>$thread2</i></li>
<p>Evaluates to true iff <i>$thread1</i> and <i>$thread2</i> reference the same
<code>Thread</code> object.</p>
<li><a name='Thread::yield()'></a><code>Thread::yield</code>()</li>
<p>Gives the interpreter an opportunity to switch to another thread. The
interpreter is not obligated to take this opportunity, and the calling
thread may regain control after an arbitrarily short period of time.</p>
</ul>
<a name='Critical section'></a><h2>Critical section</h2>
<p><code>critical</code> is a new keyword. Syntactically, it works like <code>do</code>.</p>
<pre>  critical { ... }; </pre>
<p>The interpreter guarantees that only one thread at a time can execute
a <code>critical</code> block.</p>
<a name='Lock'></a><h2>Lock</h2>
<p><code>lock</code> applies a lock to a variable.
In void context, it blocks until it acquires the lock.
In non-void context, it does not block, and returns <code>true</code> or
<code>false</code> according as the thread does or does not acquire the lock.</p>
<ul>
<li><a name='lock $scalar'></a><code>lock</code> <i>$scalar</i></li>
<li><a name='lock @array'></a><code>lock</code> <i>@array</i></li>
<li><a name='lock %hash'></a><code>lock</code> <i>%hash</i></li>
<li><a name='lock &amp;sub'></a><code>lock</code> <i>&amp;sub</i></li>
<p>Applies a lock to a variable.</p>
<p>If there are no locks applied to the variable, applies a lock and
returns immediately.
If there are locks applied by another thread, blocks until there are
no locks applied.
If there are locks applied by the calling thread, applies another lock
and returns immediately.</p>
<p>The lock is automatically removed at the end of the lexical scope in
which the <code>lock</code> operator executes.</p>
<li><a name='$ok = lock $scalar'></a><i>$ok</i> = <code>lock</code> <i>$scalar</i></li>
<li><a name='$ok = lock @array'></a><i>$ok</i> = <code>lock</code> <i>@array</i></li>
<li><a name='$ok = lock %hash'></a><i>$ok</i> = <code>lock</code> <i>%hash</i></li>
<li><a name='$ok = lock &amp;sub'></a><i>$ok</i> = <code>lock</code> <i>&amp;sub</i></li>
<p>Tries to apply a lock to a variable.</p>
<p>If there are no locks applied to the variable, applies a lock and
returns true.
If there are locks applied by another thread, returns false.
If there are locks applied by the calling thread, applies another lock
and returns true.</p>
<p>The lock is automatically removed at the end of the lexical scope in
which the <code>lock</code> operator executes.</p>
<li><a name='unlock $scalar'></a><code>unlock</code> <i>$scalar</i></li>
<li><a name='unlock @array'></a><code>unlock</code> <i>@array</i></li>
<li><a name='unlock %hash'></a><code>unlock</code> <i>%hash</i></li>
<li><a name='unlock &amp;sub'></a><code>unlock</code> <i>&amp;sub</i></li>
<p>Removes a lock from a variable.</p>
<p>If there are locks applied by the calling thread, removes one.
If there are locks applied by another thread, does nothing.
If there are no locks applied to the variable, does nothing.</p>
<p><code>unlock</code> never blocks.</p>
</ul>
<p>A consequence of these rules is that only one thread at a time may have
locks applied to a variable.</p>
<a name='Condition variables'></a><h2>Condition variables</h2>
<ul>
<li><a name='cond_wait $mutex'></a><code>cond_wait</code> <i>$mutex</i></li>
<p><i>$mutex</i> may be any variable.</p>
<p><i>$mutex</i> must be <code>lock</code>ed before calling <code>cond_wait</code>. <code>cond_wait</code>
atomically unlocks <i>$mutex</i> and blocks waiting for a signal from a
<code>cond_signal</code>(<i>$mutex</i>) or <code>cond_broadcast</code>(<i>$mutex</i>) call.</p>
<p>When a signal from a <code>cond_signal</code>(<i>$mutex</i>) or
<code>cond_broadcast</code>(<i>$mutex</i>) call is received, <code>cond_wait</code> atomically
unblocks the calling thread and reacquires a lock on <i>$mutex</i>.</p>
<li><a name='cond_signal $mutex'></a><code>cond_signal</code> <i>$mutex</i></li>
<p>Sends a signal to one (arbitrarily chosen) thread that is blocked in
a <code>wait_cond</code>(<i>$mutex</i>) call.</p>
<li><a name='cond_broadcast $mutex'></a><code>cond_broadcast</code> <i>$mutex</i></li>
<p>Sends a signal to all threads that are blocked in
<code>wait_cond</code>(<i>$mutex</i>) calls.</p>
</ul>
<p>This only documents the interface to the <code>cond_</code>xxx calls. Using
condition variables to synchronize threads requires additional code.
See, for example,</p>
<pre>      <a href='http://uw7doc.sco.com/SDK_sysprog/_Condition_Variables.html' target='_blank'>uw7doc.sco.com</a></pre>
<a name='Timers'></a><h2>Timers</h2>
<ul>
<li><a name='Thread::delay $seconds'></a><code>Thread::delay</code> <i>$seconds</i></li>
<p>Blocks for <i>$seconds</i> seconds. <i>$seconds</i> may be a floating point
number, so this interface supports whatever time resolution the
platform provides.</p>
<li><a name='Thread::alarm $time'></a><code>Thread::alarm</code> <i>$time</i></li>
<p>Blocks until <i>$time</i> seconds after the epoch. <i>$time</i> may be a
floating point number, so this interface supports whatever time
resolution the platform provides.</p>
</ul>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>All of these features should be doable if threads are built into Perl.</p>
<a name='DISCUSSION'></a><h1>DISCUSSION</h1>
<p>This interface is an amalgam of</p>
<ul>
<li><a name='the Thread.pm interface from Perl 5.6.0'></a>the <code>Thread.pm</code> interface from Perl 5.6.0</li>
<li><a name='the Win32 thread interface'></a>the Win32 thread interface</li>
<li><a name='my own wish list (you can't get it if you don't ask...)'></a>my own wish list (you can't get it if you don't ask...)</li>
</ul>
<p>Here are some issues to consider</p>
<a name='Thread creation'></a><h2>Thread creation</h2>
<p>Threads are created by</p>
<pre>  new Thread \&amp;func
  new Thread sub { ... }
  async { ... }</pre>
<p>We arguably don't need three different ways to create threads.
However, the different syntaxes fit into the language in slightly
different ways, and I'm not sure which one I'd be willing to give up.
The first is the most fundamental; losing it would be a serious
inconvenience. Perl generally allows an anonymous subroutine where
ever it allows a code ref, so the second also seems appropriate. And
the third allows us to create threads with the kind of lightweight
syntax that makes Perl such a lucid language.</p>
<a name='join'></a><h2><code>join</code></h2>
<p>The calling context of <code>join</code> can't be propagated into the thread,
for several reasons.</p>
<ul>
<li><a name='The thread can compute only one return value, but join can be called repeatedly in different contexts.'></a>The thread can compute only one return value, but <code>join</code> can be
called repeatedly in different contexts.</li>
<li><a name='The thread might terminate before the first call to join. join can return the last expression evaluated in the thread, but it can't retroactively affect the context in which that expression was evaluated.'></a>The thread might terminate before the first call to join. <code>join</code> can
return the last expression evaluated in the thread, but it can't
retroactively affect the context in which that expression was evaluated.</li>
</ul>
<p>Not allowing multiple <code>join</code>s on a thread might help with the first
problem; I can't see any way around the second.</p>
<a name='Critical sections'></a><h2>Critical sections</h2>
<p>This interface provides the</p>
<pre>  critical { ... } </pre>
<p>construct. In principle, we don't need this: you can do the same thing
with scoped locks</p>
<pre>  sub foo
  {
      lock &amp;foo;
      ...
  }

  sub bar
  {
      {
      lock $bar::a;
      ...
      }

      {
      lock $bar::b;
      ...
      }
  }</pre>
<p>Nonetheless, critical sections have several attractive features.</p>
<ul>
<li><a name='They reduce clutter. No named variable to lock.'></a>They reduce clutter. No named variable to lock.</li>
<li><a name='Along with less clutter comes fewer chances for bugs. There isn't a locked variable floating around to get locked by the wrong thread, or locked and never unlocked, or deadlocked, or...'></a>Along with less clutter comes fewer chances for bugs. There isn't a
locked variable floating around to get locked by the wrong thread, or
locked and never unlocked, or deadlocked, or...</li>
<li><a name='The implementation can be highly optimized. Internally, a critical section is protected by some kind of mutex. However, this mutex isn't user visible: the interpreter has complete control over it. Therefore, it can be very lightweight.'></a>The implementation can be highly optimized. Internally, a critical
section is protected by some kind of mutex. However, this mutex isn't
user visible: the interpreter has complete control over it. Therefore,
it can be very lightweight.</li>
</ul>
<p>Efficiency matters, because critical sections are used to manage things that
are...well...critical. Important, global, high-contention resources like
memory managers and process schedulers. Granted, these are poor
examples for Perl, but you get the idea.</p>
<p>Whether to implement <code>critical</code> depends partly on whether serializing
execution of a block of code is common enough to merit its own keyword
and syntax. Threads.pm in Perl 5.6.0 documents a <code>:locked</code> attribute
for subroutines; given a choice, I'd rather have <code>critical</code> than
<code>:locked</code>.</p>
<a name='Locked variables'></a><h2>Locked variables</h2>
<p>Version 3 of this RFC proposed <code>try</code> to acquire a lock without
blocking. <code>try</code> does not block, and returns <code>true</code> or <code>false</code>
according as the thread does or does not acquire the lock.</p>
<p>It was pointed out that the keyword <code>try</code> will likely be taken for
exception handling. There are several ways we could avoid conflict</p>
<ul>
<li><a name='Choose another name, like try_lock.'></a>Choose another name, like <code>try_lock</code>.</li>
<pre>    try_lock $mutex and ...</pre>
<li><a name='Push try down into the Thread:: package.'></a>Push <code>try</code> down into the <code>Thread::</code> package.</li>
<pre>    Thread::try $mutex and ...</pre>
<li><a name='Or (my favorite) overload lock on its calling context.'></a>Or (my favorite) overload <code>lock</code> on its calling context.</li>
</ul>
<p>This RFC currently documents the last alternative.</p>
<a name='Condition variables'></a><h2>Condition variables</h2>
<p>I found out how to use condition variables. See, for example,</p>
<pre>    <a href='http://uw7doc.sco.com/SDK_sysprog/_Condition_Variables.html' target='_blank'>uw7doc.sco.com</a></pre>
<p>You can build events out of condition variables, and a lot of other
things besides. I'm pretty sure you can build <code>wait_any</code> with
condition variables. It seems like you should be able to build
<code>wait_all</code>, but I haven't yet figured out how.</p>
<p>In any case, I'd rather have condition variables than a menagerie of
other synchronization primitives.</p>
<a name='I/O'></a><h2>I/O</h2>
<p>I dropped the I/O section, because you can use condition variables
to block on I/O in a controlled fashion</p>
<pre>  async { connect($sock, $addr); $connected=1; cond_signal($sock); }
  async { Thread::delay(10);     $timed_out=1; cond_signal($sock); }
  async { &lt;STDIN&gt;;               $canceled =1; cond_signal($sock); }

  lock $sock;
  cond_wait($sock);
  $connected and ...
  $timed_out and ...
  $canceled  and ...</pre>
<a name='Event, Semaphore, and Queue'></a><h2>Event, Semaphore, and Queue</h2>
<p>You can build all these from mutexes and condition variables.</p>
<a name='Wait functions'></a><h2>Wait functions</h2>
<p>I dropped the wait functions from this interface. You can build
<code>wait_any</code> from condition variables. I'm not sure whether or not you
can build <code>wait_all</code>. However, a built-in <code>wait_all</code> function would
be limited to waiting on existing synchronization primitives. This
could make it somewhat rigid, and possibly of limited utility.</p>
<a name='die'></a><h2><code>die</code></h2>
<p>I dropped the <i>$thread</i>-&gt;<code>eval</code> call from this interface, and didn't
say what happens if a thread <code>die</code>s. There are several possibilities</p>
<ul>
<li><a name='The exception is propagated to any thread that joins it. This has a certain logic to it, but it suffers from the fact that a program needn't join its threads, so it doesn't guarantee that exceptions will actually be handled.'></a>The exception is propagated to any thread that <code>join</code>s it. This has a
certain logic to it, but it suffers from the fact that a program
needn't <code>join</code> its threads, so it doesn't guarantee that exceptions
will actually be handled.</li>
<li><a name='The interpreter prints $@ on stderr and exits. This is what C++ does. It ensures that exceptions won't just disappear into the void; however, it also causes a good deal of anxiety and paranoia, because any thread can potentially blow your program out of the water. (I speak from experience here.)'></a>The interpreter prints <code>$@</code> on stderr and exits. This is what C++
does. It ensures that exceptions won't just disappear into the void;
however, it also causes a good deal of anxiety and paranoia, because
<i>any</i> thread can potentially blow your program out of the water. (I
speak from experience here.)</li>
<li><a name='The thread just quietly goes away. After working with threads in C++, I'm actually partial to this one. We still need some way to recover $@ when a thread dies. Returning $@ to join is probably the Wrong Thing.'></a>The thread just quietly goes away. After working with threads in C++,
I'm actually partial to this one. We still need some way to recover
<code>$@</code> when a thread <code>die</code>s. Returning <code>$@</code> to <code>join</code> is probably
the Wrong Thing.</li>
</ul>
<a name='=='></a><h2><code>==</code></h2>
<p>I dropped <i>$thread</i>-&gt;<code>equal</code> in favor of overloading <code>==</code> to
compare threads. This seems more natural, and should be easy to
implement if threads are built into the language.</p>
<a name='Thread IDs'></a><h2>Thread IDs</h2>
<p>I dropped thread IDs from the interface. You don't want thread IDs.
Thread IDs are an implementation artifact. Carrying around explicit
numerical indices isn't the Perl way. They were broken anyway (wrap at
2^32, with no guarantee of uniqueness after that).</p>
<a name='Detach'></a><h2>Detach</h2>
<p>I dropped <code>detach</code> from the interface. Detach is an artifact of
languages that require programmers to manage their own storage. It has
rigorous semantics, there's no going back, and if you get it wrong,
you either leak threads or you crash.</p>
<p>In Perl, detachment is more a state of mind. We have threads, and we
have <code>Thread</code> objects to manage them. The thread holds a reference on
its <code>Thread</code> object until it terminates. The <code>Thread</code> object holds a
reference on its thread as long as the <code>Thread</code> object exists.</p>
<p>If there are no user-visible references to a <code>Thread</code> object (i.e.
the only reference on the <code>Thread</code> object is the one held by the
thread), then the thread is said to be detached. A call to
<code>Thread</code>-&gt;<code>all</code> or <code>Thread</code>-&gt;<code>this</code> could recover a reference to
the <code>Thread</code> object of a detached thread; when this happens, the
thread is no longer detached.</p>
<p>In any case, you don't have to worry about it. Like so many others,
<code>detach</code> is a problem that Perl doesn't have.</p>
<a name='Import'></a><h2>Import</h2>
<p>To minimize namespace pollution, we could @EXPORT_OK the functions
that appear in this interface.</p>
<pre>  use Threads qw(yield delay alarm)</pre>
<p>On the other hand, if they get moved into the core the issue may be
moot.</p>
<a name='Timer'></a><h2>Timer</h2>
<p>There are two kinds of timers: relative and absolute. Obviously, you
can always build one kind out of the other, but I wanted to
distinguish them with different constructors. I named the constructors
<code>delay</code> and <code>alarm</code>, respectively. These are short, and read fairly
naturally.</p>
<a name='this Thread'></a><h2><code>this Thread</code></h2>
<p>C++ partisans will get brain freeze reading code like</p>
<pre>  my $thread = this Thread;</pre>
<p>but that's not why I traded in <code>self</code> for <code>this</code>. Really, it's not.
I did it because it reads more naturally to me.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 1: Implementation of Threads in Perl</p>
<p>RFC 27: Coroutines for Perl</p>
<p>RFC 31: Subroutines: Co-routines</p>
<p>RFC 47: Universal Asynchronous I/O</p>
<p>RFC 178: Lightweight Threads</p>
<p>Threads.pm</p>
<p>PThreads info page</p>
<p><a href='http://uw7doc.sco.com/SDK_sysprog/_Condition_Variables.html' target='_blank'>uw7doc.sco.com</a></p>
</div>
